CSR Enrollment

The certificate signing requestClosed A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. (CSRClosed A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA.) enrollmentClosed Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). page provides the ability to submit a CSR and download the resulting certificate.

Important:  Before you can use the CSR enrollment function, you must:
Note:  The following algorithms are supported as the primary key for enrollment:
Important:  A ML-DSA primary key cannot be used for a hybrid certificateClosed A certificate with both a standard key and a post-quantum key. (a certificate with both a primary and alternative key).

The following algorithms are supported as the alternative key for enrollment:

  • ML-DSA-44
  • ML-DSA-65
  • ML-DSA-87

The availability of these algorithms depends on the following factors:

When configuring key information policies at the enrollment pattern level, only key sizes that are valid for the selected algorithm will be available. These sizes are determined by the system-wide policy, enrollment pattern policy, and the supported key sizes in the template configuration.

For PFX enrollment and CSR generation, dropdown menus for Key Algorithm and Key Size will appear if the selected enrollment pattern’s template and policy settings support multiple options. If the template configuration or applied policy restricts the template to a single key algorithm or size, the dropdowns will be disabled (grayed out).

When ECCClosed Elliptical curve cryptography (ECC) is a public key encryption technique based on elliptic curve theory that can be used to create faster, smaller, and more efficient cryptographic keys. ECC generates keys through the properties of the elliptic curve equation instead of the traditional method of generation as the product of very large prime numbers. is selected as the key algorithm, a search-select field allows the choice of an elliptic curve. Only curves that are supported by the system-wide policy, the enrollment pattern policy, and the template’s configuration will be available in this field.

To request a certificate via CSR:

  1. Generate a CSR. This can be done within the target application (e.g. Microsoft IIS), by using a tool such as certutil or OpenSSL, or by using the Keyfactor Command CSR generation tool (see CSR Generation). Have the CSR file ready.
  2. In the Management Portal, browse to Enrollment > CSR Enrollment.
  3. In the Certificate Request Information section, enable Use Standalone CA to enroll from a standalone CA, if applicable. This toggle appears only if you have a standalone CA configured for enrollment. Enabling this option will disable the Enrollment Pattern dropdown. Enrollment patterns are not used for standalone CA enrollments.

  4. In the Certificate Request Information section select an enrollment pattern from the Enrollment Pattern dropdown.

    The enrollment patterns are organized by configuration tenantClosed A grouping of CAs. The Microsoft concept of forests is not used in EJBCA so to accommodate the new EJBCA functionality, and to avoid confusion, the term forest needed to be renamed. The new name is configuration tenant. For EJBCA, there would be one configuration tenant per EJBCA server install. For Microsoft, there would be one per forest. Note that configuration tenants cannot be mixed, so Microsoft and EJBCA cannot exist on the same configuration tenant. (formerly known as forestClosed An Active Directory forest (AD forest) is the top most logical container in an Active Directory configuration that contains domains, and objects such as users and computers.). If you have multiple configuration tenants and enrollment patterns with similar names, be sure to select the enrollment pattern in the correct configuration tenant.

    Tip:  If you paste the contents of your generated certificate file before selecting an enrollment pattern, the CSR Content and the CSR Name tabs will be erased. You will need to re-paste the certificate data once you have selected an enrollment pattern.

    Figure 99: Select an Enrollment Pattern

  5. Select the Certificate Authority from which the certificate should be requested, or select Auto-Select.

    Note:   The list of CAs that appears in the dropdown depends on the enrollment pattern's Restrict CAs setting (see Enrollment Pattern: Basic Information Tab) and the configuration tenant of the template associated with the enrollment pattern:

    • Restrict CAs Enabled: The CAs listed in the enrollment pattern’s Certificate Authorities list, limited to those in the same configuration tenant as the associated template.

    • Restrict CAs Disabled: All enterprise CAs defined in Keyfactor Command that share the same configuration tenant as the associated template.

    In either case, in order for the CA to appear in the dropdown:

    • The CA must have the Use for Enrollment option enabled in Keyfactor Command.

    • The template associated with the enrollment pattern must be available for enrollment on the CA.

    • The template must have certificate request permissions granted to the appropriate user (see HTTPS CAs - Advanced Tab or DCOM CAs - Advanced Tab).

    If Auto-Select is chosen, a certificate authority (CA) will be randomly selected from the CAs available for enrollment with the specified enrollment pattern, which depends on the configuration of the RestrictCAs setting as noted above. Auto-Select is not an option when enrollment is being done against a standalone CA.

    Standalone CAs do not use templates or enrollment patterns and will be shown if certificate request permissions on the CA have been granted to the appropriate user (see HTTPS CAs - Advanced Tab or DCOM CAs - Advanced Tab).

  6. Paste your CSR into the CSR Content text area, with or without the BEGIN REQUEST/END REQUEST delimiters.

    Figure 100: CSR Enrollment: CSR Content

  7. The CSR contents will be parsed, and you will automatically be switched to the CSR Names view. Review the data to be sure it is as expected.

    Note:  If you are enrolling against an EJBCA CA, by default the total SANClosed The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. length cannot exceed 2000 characters. If you need to enter SANs that will cause the total length to exceed this maximum, or if you need support for a custom SAN type, see Appendix - Configuring Support for Large or Custom SANs with EJBCA.

    Microsoft CAs by default support a total SAN size of 4k. If you need to enter SANs that will cause the total size to exceed this, please refer to this article:

    https://learn.microsoft.com/en-us/troubleshoot/windows-server/certificates-and-public-key-infrastructure-pki/expand-maximum-extension-size-limit-ad-cs#expand-the-limit-by-using-an-administrative-command-prompt

    Figure 101: CSR Enrollment: CSR Names

    Note:  If a regular expressionClosed A regular expression--RegEx--is a pattern used to validate data by ensuring it meets specific criteria. Several fields on the CSR enrollment, CSR generation, and PFX enrollment pages support RegEx validation, including certificate subject and metadata fields. is defined system-wide or at the enrollment pattern level (see Enrollment Pattern: Enrollment RegExes Tab) for a subject part or SAN, and that field is left blank, the regular expression will still be applied to an empty string. For example, if a regular expression is defined for the organization field but no organization is provided, the system treats the empty string as the input and applies the regular expression accordingly.

  8. If enrollment fields have been defined for the selected enrollment pattern (see Enrollment Pattern: Enrollment Fields Tab), the fields will display in the Additional Enrollment Fields section. Additional enrollment fields have a data type of either string or multiple choice. String fields will appear as a text box; multiple choice fields will appear as a dropdown. All additional enrollment fields are required.

    Figure 102: Populate Enrollment Fields

  9. In the Certificate Metadata section of the page, populate any defined certificate metadataClosed Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. fields (see Certificate Metadata, Configuring Template Options, and Adding or Modifying an Enrollment Pattern) as appropriate. These fields may be required or optional depending on your metadata configuration. Required fields will be marked with *Required next to the field label. Any completed values will be associated with the certificate once it has been synchronized with Keyfactor Command. The order in which the metadata fields appear can be changed (see Sorting Metadata Fields).

    Tip:  If a hint has been provided for a specific metadata field, it will display in parentheses to the right of the metadata label.

    Figure 103: Populate Metadata Fields

  10. The Subject Alternative Names (SANs) section of the page appears if you enable the Allow CSR SAN Entry application setting (see Application Settings: Enrollment Tab). This option is disabled by default. Click Add to add SANs if needed. In the Add SANs dialog, select a Type in the dropdown and in the Value box add one or more SANs of the selected type and save. Only SANs of a single type may be added in a single add action. Click Edit to change a SAN field. The Edit SAN dialog includes only one SAN, not the multi-SAN block. Click Delete to delete a SAN.

    The SAN field in this interface supports: DNS name, IP version 4 address, IP version 6 address, User Principle Name, Email. Alternate SANs may be submitted in requests using the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command..

    Note:  If you are enrolling against an EJBCA CA, by default the total SAN length cannot exceed 2000 characters. If you need to enter SANs that will cause the total length to exceed this maximum, see Appendix - Configuring Support for Large or Custom SANs with EJBCA.

    Microsoft CAs by default support a total SAN size of 4k. If you need to enter SANs that will cause the total size to exceed this, please refer to this article:

    https://learn.microsoft.com/en-us/troubleshoot/windows-server/certificates-and-public-key-infrastructure-pki/expand-maximum-extension-size-limit-ad-cs#expand-the-limit-by-using-an-administrative-command-prompt

    Figure 104: CSR Enrollment SAN options

    Important:  If the Enforce RFC 2818 Compliance option has been enabled for the selected enrollment pattern (see Enrollment Pattern Operations) or system-wide, a SAN will automatically be added with a DNSClosed The Domain Name System is a service that translates names into IP addresses. SAN matching the CNClosed A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). entered for the certificate if one is not included in the CSR. This SAN will not appear in the grid and cannot be edited.
    Note:  SANs submitted outside the CSR may be ignored, appended to SANs in the CSR, or overwrite the SANs in the CSR request depending on the type and configuration of the issuing CA. Please be sure to check that the certificate has the correct SANs after issuance. Any SAN added automatically as a result of the RFC 2818 compliance settings will still be added alongside anything you add here. For a Microsoft CA, review the SAN Attribute Policy Handler for the Keyfactor CA Policy Module (see Installing the Keyfactor CA Policy Module Handlers) for more information.

  11. The Certificate Owner section of the page appears if you set the Certificate Owner Role policy to Optional or Required at either the system-wide or enrollment policy level (see Configuring System-Wide Settings and Enrollment Pattern: Policies Tab). The certificate owner refers to a security role (not the users, individually), as defined in Keyfactor Command (see Security Roles and Claims). The Owner Role Name is a search select field. To narrow the list of results in the search select field, begin typing a search string in the search field. The roles available to choose from will depend on the certificate security configuration for the user (see security roles and permissions for Certificates).

    In all cases, the owner role field behavior, optional, required or hidden in the UI, is controlled by either the enrollment pattern system-wide policy or the individual enrollment pattern policy. The field will be pre-populated with the default certificate owner, if set, on the enrollment pattern, unless the acting user is not a member of the default user roles.

    • Expanded Change Owner Permission: A user who holds the Certificates > Expanded Change Owner permission can set the certificate owner to any role within the permission sets they are a member of. This permission setting overrides the Certificates > Collections > Change Owner permission (both Global and CollectionClosed The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports).-level) if both are set.

    • Collections > Change Owner Permission:

      • Global or Collection Level—No Default Value: A user who holds only the Certificates > Collections > Change Owner permission at either the Global or Collection level can set the certificate owner to any role they belong to if there is not a default value populated from the enrollment pattern or existing certificate on a renewal.
      • Global or Collection Level—Default Value: A user who holds only the Certificates > Collections > Change Owner permission at either the Global or Collection level can change the default certificate owner to any role they belong to. If the default value populated from the enrollment pattern or existing certificate on a renewal is not a role held by the acting user, the this value will not be populated in the Certificate Owner Role field. The user will still be allowed to add a new owner value.
    • Search Select Disabled: The certificate owner search select is disabled if the acting user does not hold the current certificate owner role (either in a global or collection-level context).

    Figure 105: Select a Certificate Owner

  12. In the Certificate Format section of the page, select the desired File Extension. Available options are:

    .cer, .crt, or .pem

    The option you select here determines the formats that will be available in the File Format dropdown.

  13. Select a File Format. Available options will depend on the selected File Extension and may include:

  14. Te Chain Options section will display only when the File Format is PEM. Toggle Include Chain to On if you want the certificate chain to be included with the returned certificate. The default value is set in the enrollment application setting: Include Chain By Default.

    15. Note:  In order for chain certificates to be included with end entity certificates for download, one of the following must be true:

  15. The Include Subject Header toggle is displayed in the Additional Options section of the page only when the File Format is PEM. The default value is On. When set to Off, the first line in the PEM file—containing the certificate’s subject information—is removed. When set to On the first line in the PEM file—that containing the certificate’s subject information—is included.

  16. Click the Enroll button to begin the certificate request process.

    Note:  If you attempt to complete a CSR enrollment using a CSR generated within Keyfactor Command, you will receive a Confirm Operation message requiring you to click OK to confirm and enroll unless the Enable warning for CSR generated in Command application setting has been disabled.

    • When renewing, if the Enable warning for CSR renewal with a Subject/SAN mismatch application setting is enabled, the CSR enrollment page will throw a warning on submission if the SANs/Subject are different from the SANs/Subject of the certificate that is being renewed.

    Click OK on this popup to ignore the warning (see Application Settings: Enrollment Tab).

    Figure 106: CSR Warning Message

    Tip:  The filename generated for the file for download is based on the CN of the certificate and will either include or not include the periods from the CN based on the configuration of the Allow Periods in Certificate Filenames application setting (see Application Settings: Enrollment Tab).
Note:  All enrollment (PFXClosed A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers., ODKG and CSR), renewal, and revocation requests flow through Keyfactor Command workflow (see Workflow Definitions).
Tip:  Click the help icon () next to the CSR Enrollment page title to open the Keyfactor Software & Documentation Portal to this section. You will receive a prompt indicating:

You are being redirected to an external website. Would you like to proceed?

You can also find the help icon () at the top of the page next to the Log Out button. From here you can choose to open either the Keyfactor Software & Documentation Portal at the home page or the Keyfactor API Endpoint Utility.

Keyfactor provides two sets of documentation: the On-Premises Documentation Suite and the Managed Services Documentation Suite. Which documentation set is accessed is determined by the Application Settings: On-Prem Documentation setting (see Application Settings: Console Tab).